# Preâmbulo {#preambulo}

O preâmbulo é a parte do documento `principal.tex` onde você define os principais aspectos relacionados
à formatação final do seu documento acadêmico.

## Tipo de documento

A primeira, e mais importante, definição feita no preâmbulo do documento `principal.tex` é quanto ao tipo de 
documento acadêmico suportado pela classe `UFRuralRJ`. Isso é feito usando o comando:

    %% Tipo de documento
    \documentclass[<opções>]{<classe>}

No momento, a classe `UFRuralRJ` suporta dois tipos de documento acadêmico: dissertação e tese. Se você 
estiver trabalhando em sua *tese*, use a opção `tese`. Mas se estiver trabalhando em sua *dissertação*, use a
opção `diss`. Veja o exemplo:

    %% Tipo de documento
    \documentclass[tese]{UFRuralRJ}

Outras quatro opções auxiliares estão disponíveis para esses dois tipos de documento acadêmico:

* `twoside` e `openright`: Essas duas opções devem ser sempre usadas em conjunto a fim de formatar o 
  documento acadêmico de acordo com o MANUAL quando o mesmo será impresso em frente e verso. Todos os itens da
  parte preliminar são impressos sempre na página ímpar, ou seja, na página do lado direito. Da mesma forma, 
  a primeira página de cada item principal do corpo do documento acadêmico sempre é impressa na página ímpar, 
  ou seja, na página do lado direito.
* `header`: Adiciona cabeçalho às páginas do documento acadêmico, exceto na parte preliminar (sumário, 
  prefácio etc) e na página inicial de cada item principal do corpo do documento acadêmico. O cabeçalho é
  constituído por uma barra horizontal e por uma versão curta do título to respectivo item principal 
  (capítulo). Veja abaixo o comando `\shorttitle{<título curto>}` usado para definir a versão curta do título 
  dos itens principais. Note que o MANUAL não prevê a inclusão de cabeçalho nas páginas dos documentos 
  acadêmicos.
* `newmargins`: Redefine as dimensões das margens das páginas do documento acadêmico a fim de redistribuir
  melhor o conteúdo na página usando alinhamento centralizado. Para isso, as margens originais superior e 
  interior (30 mm), e inferior e exterior (20 mm) são redefinidas da seguinte maneira: superior e inferior = 
  25 mm; interior e exterior (laterais) = 20 mm. Essa opção é útil na produção do arquivo em formato PDF que
  será usado para disponibilizar o documento acadêmico em meio digital. Note que o MANUAL não prevê essas 
  dimensões para as margens das páginas.

O exemplo abaixo declara que estamos preparando uma *tese* que será impressa em frente e verso, e cujas
páginas contém cabeçalho:

    %% Tipo de documento
    \documentclass[tese, header, twoside, openright]{UFRuralRJ}

## Pacotes

Depois de definir o tipo de documento que será produzido, bem como alguns dos aspectos básicos da sua 
formatação, é preciso declarar quais pacotes serão usados como suporte adicional à formatação do documento
acadêmico. Isso é feito usando o comando:

    %% Pacotes
    \usepackage[<opções>]{<pacote>}

### Língua, codificação e fonte

Vários pacotes estão disponíveis, mas aqui apenas alguns de maior importância serão apresentados. Por exemplo, 
o fato de usamos acentuação na língua portuguesa requer que usemos pacotes que identifiquem corretamente os 
símbolos usados para a acentuação. Veja alguns exemplos:
    
    %% Pacotes - língua, codificação e fonte
    \usepackage[brazilian]{babel}
    \usepackage[T1]{fontenc}
    \usepackage[utf8]{inputenc}

### Hiperlinks

Outro pacote de grande utilidade é [`hyperref`][hyperref], o qual permite inserir hiperlinks no documento 
acadêmico. Hiperlinks são de grande utilidade quando o documento é publicado no formato PDF. Para carregar
o pacote `hyperref` usa-se o seguinte comando:

    %% Pacotes - formatação de hyperlinks e urls
    \usepackage[%hidelinks%, 
                bookmarksopen=true, linktoc=page, colorlinks=true,
                linkcolor=blue, citecolor=blue, filecolor=magenta, urlcolor=blue,
                pdftitle={UFRuralRJ -- Classe LaTeX para formatação de documentos acadêmicos na UFRRJ},
                pdfauthor={Graziela Barroso},
                pdfsubject={Tese de Doutorado},
                pdfkeywords={LaTeX, UFRuralRJ, Documentos acadêmicos}
                ]{hyperref}

O pacote `hyperref` possui uma série de opções, as quais são definidas dentro do espaço delimitado pelos 
colchetes no comando `\usepackage[<opções>]{<pacote>}`. Essas opções permitem, por exemplo, definir a cor dos 
hiperlinks no texto, bem como atribuir propriedades ao documento PDF resultante tais como o seu título e autor.

### Citações e referências bibliográficas

O pacote usado para formatar as citações no texto e a lista de referências bibliográficas no final do documento 
acadẽmico conforme as normas da Associação Brasileira de Normas Técnicas (ABNT) é o 
[`abntex2cite`][abntex2cite].

    %% Pacotes - formatação da bibliografia de acordo com as normas da ABNT
    \usepackage[alf, abnt-etal-cite=2, abnt-etal-list = 0]{abntex2cite}

Com o pacote `abntex2cite` você está livre do árduo trabalho de formatar as citações e a lista de referências 
bibliográficas. A única exigência, é claro, é que você tenha todos os dados de suas referências bibliográficas 
organizados em uma base de dados.

NOTA: O pacote `abntex2cite` precisa, obrigatoriamente, ser carregado depois do pacote `hyperref`.

## Dados para elementos pré-textuais

### Identificação do trabalho

Ainda no preâmbulo do documento definimos uma série de parâmetros que serão usados pela classe `UFRuralRJ` para
construir as páginas iniciais do documento acadêmico, ou seja, a capa, a folha de rosto, a folha de aprovação,
e o resumo. Esses são os elementos pré-textuais do documento acadêmico. Considere o seguinte exemplo de dados 
de identificação do trabalho:

    %% Identificação do trabalho
    \titulo{UFRuralRJ -- Classe \LaTeX{} para Formatação de Documentos 
            Acadêmicos na UFRRJ}
    \author{Barroso}{Graziela}
    \autoratrue
    \instituto{Instituto de Agronomia}
    \curso{Curso de Pós-Graduação em Agronomia -- Ciência do Solo}
    \area{Ciência do Solo}
    \local{Seropédica}{RJ}{Brasil}

O comando `\titulo{<titulo do documento>}` é utilizado para definir o título do trabalho acadêmico, enquanto o 
comando `\author{<sobrenome do autor>}{<nome do autor>}` serve para identificar o autor, sendo informado 
primeiro o sobrenome, e depois o nome.

Note que após a definição do nome do autor, usamos o comando `\autoratrue`. Esse comando serve para informar a 
classe `UFRuralRJ` que o autor é do gênero feminino, ou seja, trata-se de uma autora. Qual a importância disso?
Bem, a class `UFRuralRJ` foi arquitetada de maneira a lidar, automaticamente, com as definições relacionadas ao
gênero do autor. Por exemplo, no caso de uma tese elaborada por um autor do gênero feminino, a classe 
`UFRuralRJ` identificará automaticamente que o título atribuído é de *doutora* ao invés de *doutor*, desde que 
o comando `\autoratrue` seja utilizado. Caso o autor seja do gênero masculino, basta remover o comando 
`\autoratrue` do documento, ou substituí-lo pelo comando contrário `\autorafalse`.

A utilidade do próximo comando usado na identificação do trabalho é bastante óbvia. 
`\instituto{<nome do instituto>}` refere-se ao nome do instituto da UFRRJ no qual o curso de pós-graduação está
lotado. No exemplo acima o nome do instituto foi inserido por extenso (Instituto de Agronomia). Contudo, também
poderia ter sido usado o comando `\IA`, ou seja, `\instituto{\IA}`. Outros comandos disponíveis para definir o 
nome do instituto são:

* `\IA`: Instituto de Agronomia
* `\IB`: Instituto de Ciências Biológicas e da Saúde
* `\ICE`: Instituto de Ciências Exatas
* `\ICHS`: Instituto de Ciências Humanas e Sociais
* `\IE`: Instituto de Educação
* `\IF`: Instituto de Florestas
* `\IM`: Instituto Multidisciplinar
* `\IT`: Instituto de Tecnologia
* `\IV`: Instituto de Veterinária
* `\IZ`: Instituto de Zootecnia

O comando `\curso{<nome do curso>}`, como pode-se adivinhar, serve para definir o nome do seu curso de
pós-graduação. Talvez, num futuro próximo, `UFRuralRJ` também incluirá comandos com os nomes dos cursos de 
pós-graduação assim como mostrado acima para os institutos. Segue-se que `\area{<area de concentracao>}` serve
para definir a área de concentração do trabalho acadêmico e/ou do curso de pós-graduação. Enquanto isso, 
`\local{<cidade>}{<estado>}{<país>}` especifica o local da defesa, o qual deve estar na seguinte ordem: cidade,
estado, país. Note que a opção da classe `UFRuralRJ` é por não traduzir nomes próprios em português para outras
línguas. Assim, o nome da universidade, do instituto, e do curso de pós-graduação aparecem sempre em português.

### Identificação dos orientadores

Na sequência é preciso informar a classe `UFRuralRJ` a cerca dos seus orientadores. Esses dados são usados para
construir a folha de rosto do seu documento acadêmico. Suponhamos que o seu orientador seja do gênero feminino,
ou seja, uma orientadora, e que, além dela, você possua dos orientadores. Nesse caso, os dados a cerca dos 
seus orientadores devem ser informados da seguinte maneira:

    %% Identificação dos orientadores
    \advisor[Professora]{Dra.}{Dobereimer}{Johana}{UFRRJ}
    \coadvisor[Pesquisador]{Dr.}{Salles}{Hilton}
    \coadvisor[Professor]{Dr.}{Costa}{Fernando}
    
Como você pode ver, todas as informações a cerca do orientador são passadas à classe `UFRuralRJ` usando o 
comando

    \advisor[<cargo>]{<título>}{<sobrenome>}{<nome>}{<instituição>}

Esse comando inclui o cargo ocupado na Universidade (Professor, Pesquisador), o maior título acadêmico 
obtido (Dr., Dra., MSc.), e a sigla da instituição onde está lotado. Assim como no nome do autor do 
documento acadêmico, primeiro informa-se o sobrenome e depois o nome do orientador. As mesmas regras valem 
para os coorientadores, cujas informações são passadas à class `UFRuralRJ` usando o comando 

    \coadvisor[<cargo>]{<título>}{<sobrenome>}{<nome>}

A diferença aqui é que não há necessidade de informar a sigla da instituição onde seus coorientadores estão
lotados.

### Informações sobre a defesa

Finalmente, as informações a cerca da defesa são passadas à class `UFRuralRJ` usando dois comandos: 

* `\committee[<título>]{<sobrenome>}{<nome>}{<instituição>}`
* `\date{<dia>}{<mês>}{<ano>}`

Veja o exemplo abaixo onde o comitê examinador possui cinco membros:

    %% Informações sobre a defesa
    \committee[Dr.]{Raithe}{Waldemar}{UFRRJ}
    \committee[Dra.]{Campos}{Maria Aparecida}{UFRRJ}
    \committee[Dr.]{Peçanha}{Gilberto Gastim}{UFRRJ}
    \committee[Dra.]{Souza}{Tânia Maria Melquiades de}{UFRRJ}
    \committee[Dr.]{Groszman}{Américo}{UFRRJ}
    \date{30}{02}{2001}

O comando `\committee[<título>]{<sobrenome>}{<nome>}{<instituição>}` espera quatro informações, nesta ordem: o 
maior título acadêmico (Dr., Dra., MSc.), o sobrenome, o nome, e a sigla da instituição onde está lotado. Note 
que `\committee[<título>]{<sobrenome>}{<nome>}{<instituição>}` pode ser usado tantas vezes quantos forem os 
membros do comitê examinador, sendo importante observar que a primeira ocorrência define o presidente do comitê
examinador. Em geral, o presidente do comitê examinador é o seu próprio orientador.

O comando `\date{<dia>}{<mês>}{<ano>}`, conforme pode-se adivinhar, serve para informar a data da defesa do 
documento acadêmico (na ordem dia, mês, ano), lembrando que somente números devem ser usados.
